remote-search: add an org.gnome.ShellSearchProvider2 dbus interface

We are going to change the interface, so add a new version of it.
Providers will need to opt-in to the new API.
A summary of the differences compared to the previous API:
- ActivateResult() now also takes the search terms and a timestamp as
  parameters
- a new LaunchSearch() method is added

https://bugzilla.gnome.org/show_bug.cgi?id=689735

diff --git a/data/Makefile.am b/data/Makefile.am
index 6858a4aa062cb998b55afdf641da351a6cb4f855..c998dce16812442b2495139898e53938e9e4cab0 100644 (file)
--- a/data/Makefile.am
+++ b/data/Makefile.am
@@ -11,7 +11,9 @@ desktop_DATA = gnome-shell.desktop gnome-shell-extension-prefs.desktop
 @INTLTOOL_DESKTOP_RULE@
 
 introspectiondir = $(datadir)/dbus-1/interfaces
-introspection_DATA = org.gnome.ShellSearchProvider.xml
+introspection_DATA =                           \
+       org.gnome.ShellSearchProvider.xml       \
+       org.gnome.ShellSearchProvider2.xml
 
 themedir = $(pkgdatadir)/theme
 dist_theme_DATA =                              \

diff --git a/data/org.gnome.ShellSearchProvider.xml b/data/org.gnome.ShellSearchProvider.xml
index 8a7ab2cfde94f90d174c81c526fd749ee1785d9b..48f60081bfcdd68f5a6e93969066990833764754 100644 (file)
--- a/data/org.gnome.ShellSearchProvider.xml
+++ b/data/org.gnome.ShellSearchProvider.xml
@@ -8,7 +8,7 @@
       @short_description: Search provider interface
 
       The interface used for integrating into GNOME Shell's search
-      interface.
+      interface. This interface is deprecated, and org.gnome.Shell.SearchProvider2 should be used instead.
   -->
   <interface name="org.gnome.Shell.SearchProvider">
 

diff --git a/data/org.gnome.ShellSearchProvider2.xml b/data/org.gnome.ShellSearchProvider2.xml
new file mode 100644 (file)
index 0000000..5719f09
--- /dev/null
+++ b/data/org.gnome.ShellSearchProvider2.xml
@@ -0,0 +1,85 @@
+<!DOCTYPE node PUBLIC
+'-//freedesktop//DTD D-BUS Object Introspection 1.0//EN'
+'http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd'>
+<node>
+
+  <!--
+      org.gnome.Shell.SearchProvider2:
+      @short_description: Search provider interface
+
+      The interface used for integrating into GNOME Shell's search
+      interface (version 2).
+  -->
+  <interface name="org.gnome.Shell.SearchProvider2">
+
+    <!--
+        GetInitialResultSet:
+        @terms: Array of search terms, which the provider should treat as logical AND.
+        @results: An array of result identifier strings representing items which match the given search terms. Identifiers must be unique within the provider's domain, but other than that may be chosen freely by the provider.
+
+        Called when the user first begins a search.
+    -->
+    <method name="GetInitialResultSet">
+      <arg type="as" name="terms" direction="in" />
+      <arg type="as" name="results" direction="out" />
+    </method>
+
+    <!--
+        GetSubsearchResultSet:
+        @previous_results: Array of results previously returned by GetInitialResultSet().
+        @terms: Array of updated search terms, which the provider should treat as logical AND.
+        @results: An array of result identifier strings representing items which match the given search terms. Identifiers must be unique within the provider's domain, but other than that may be chosen freely by the provider.
+
+        Called when a search is performed which is a "subsearch" of
+        the previous search, e.g. the method may return less results, but
+        not more or different results.
+
+        This allows search providers to only search through the previous
+        result set, rather than possibly performing a full re-query.
+    -->
+    <method name="GetSubsearchResultSet">
+      <arg type="as" name="previous_results" direction="in" />
+      <arg type="as" name="terms" direction="in" />
+      <arg type="as" name="results" direction="out" />
+    </method>
+
+    <!--
+        GetResultMetas:
+        @identifiers: An array of result identifiers as returned by GetInitialResultSet() or GetSubsearchResultSet()
+        @metas: A dictionary describing the given search result, containing 'id' and 'name' (both strings). Optionally, either 'gicon' (a serialized GIcon) or 'icon-data' (raw image data as (iiibiiay) - width, height, rowstride, has-alpha, bits per sample, channels, data) can be specified if the result can be better served with a thumbnail of the content (such as with images). A 'description' field (string) may also be specified if more context would help the user find the desired result.
+
+        Return an array of meta data used to display each given result
+    -->
+    <method name="GetResultMetas">
+      <arg type="as" name="identifiers" direction="in" />
+      <arg type="aa{sv}" name="metas" direction="out" />
+    </method>
+
+    <!--
+        ActivateResult:
+        @identifier: A result identifier as returned by GetInitialResultSet() or GetSubsearchResultSet()
+        @terms: Array of search terms, which the provider should treat as logical AND.
+        @timestamp: A timestamp of the user interaction that triggered this call
+
+        Called when the users chooses a given result. The result should
+        be displayed in the application associated with the corresponding
+        provider. The provided search terms can be used to allow launching a full search in
+        the application.
+    -->
+    <method name="ActivateResult">
+      <arg type="s" name="identifier" direction="in" />
+      <arg type="as" name="terms" direction="in" />
+      <arg type="u" name="timestamp" direction="in" />
+    </method>
+
+    <!--
+        LaunchSearch:
+        @terms: Array of search terms, which the provider should treat as logical AND.
+
+        Asks the search provider to launch a full search in the application for the provided terms.
+    -->
+    <method name="LaunchSearch">
+      <arg type="as" name="terms" direction="in" />
+    </method>
+  </interface>
+</node>

diff --git a/docs/reference/shell/Makefile.am b/docs/reference/shell/Makefile.am
index 2bb039542541c9c8b0bc9216310c119a48952872..ec93b23c388e579e6105543f45166a3d9b05b622 100644 (file)
--- a/docs/reference/shell/Makefile.am
+++ b/docs/reference/shell/Makefile.am
@@ -82,9 +82,17 @@ doc-gen-org.gnome.Shell.SearchProvider.xml: $(top_srcdir)/data/org.gnome.ShellSe
        --generate-docbook doc-gen                              \
        $(top_srcdir)/data/org.gnome.ShellSearchProvider.xml
 
+doc-gen-org.gnome.Shell.SearchProvider2.xml: $(top_srcdir)/data/org.gnome.ShellSearchProvider2.xml
+       gdbus-codegen                                           \
+       --interface-prefix org.gnome.ShellSearchProvider2.      \
+       --generate-docbook doc-gen                              \
+       $(top_srcdir)/data/org.gnome.ShellSearchProvider2.xml
+
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
-content_files= doc-gen-org.gnome.Shell.SearchProvider.xml
+content_files= \
+       doc-gen-org.gnome.Shell.SearchProvider.xml      \
+       doc-gen-org.gnome.Shell.SearchProvider2.xml
 
 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
 # These files must be listed here *and* in content_files

diff --git a/docs/reference/shell/shell-docs.sgml.in b/docs/reference/shell/shell-docs.sgml.in
index c2d8748037a1d954067347e400d8524633e246b3..984ea64265599577f569ef7b1c07f8dad2926adc 100644 (file)
--- a/docs/reference/shell/shell-docs.sgml.in
+++ b/docs/reference/shell/shell-docs.sgml.in
@@ -44,6 +44,7 @@
   <chapter>
     <title>Integration helpers and utilities</title>
     <xi:include href="doc-gen-org.gnome.Shell.SearchProvider.xml"/>
+    <xi:include href="doc-gen-org.gnome.Shell.SearchProvider2.xml"/>
     <xi:include href="xml/shell-global.xml"/>
     <xi:include href="xml/shell-wm.xml"/>
     <xi:include href="xml/shell-xfixes-cursor.xml"/>